---
title: Connect to a Local Network
description: Connect to a Sui local network using the Sui CLI. Use local networks to test your applications and prepare for launching them on Devnet or Testnet. 
keywords: [ local network, testnet, devnet, test application, deploy app locally, customize local network, configure local network, use local network, local network state, local faucet, using the local faucet, local sui faucet ]
---

Use a Sui local network to test your dApps against the latest changes to Sui and to prepare for the next Sui release to Devnet or Testnet. Sui CLI provides the `sui start` command to start a local network. There are several services that can be started when using `sui start`, such as an indexer, a faucet, or a local instance of the GraphQL service (including the web-based GraphiQL IDE). You can use the included faucet to get test SUI to use on the local network.

If you haven't already, you need to [install Sui CLI](/guides/developer/getting-started/sui-install.mdx) on your system.

## Start the local network

To start the local network, run the following command after you install Sui CLI.

```sh
$ RUST_LOG="off,sui_node=info" sui start --with-faucet --force-regenesis
```

This command:

- Calls the Sui CLI binary with 2 flags:
- `--with-faucet` to start a faucet service.
- `--force-regenesis` to generate a new genesis and not persist the local network state.
- Instructs Rust to set specific logging through the `RUST_LOG`=`off,sui_node=info` flags, which turns off logging for all components except `sui-node`. If you want to see more detailed logs, you can remove `RUST_LOG` from the command.

:::info
Each time you start the network by passing `--force-regenesis`, the local network starts from a random genesis with no previous data, and the local network is not persisted. If you'd like to persist data, skip passing the `--force-regenesis` flag. For more details, see the [Persist local network state](#persist-local-network-state) section. A temporary directory is created in `/tmp`, which might not work if the `/tmp` folder is mounted to `/tmpfs`. If this is the case, set `TMPDIR=./some_folder`.
:::

To customize your local Sui network, such as starting other services or changing default ports and hosts, include additional flags or options in the `sui start` command.

:::info
Options and flags like `with-indexer`, `with-graphql`, and related require you to have PostgreSQL/libpq installed. Check out the list of possible options below to find which is the default expected DB or how to pass a different DB.
:::

The following is a list of possible options and flags to pass to `sui start`:

```
    --network.config <CONFIG_DIR>
          Config directory that will be used to store network config, node db, keystore. sui genesis -f --with-faucet generates a genesis config that can be used to start this process. Use with caution as the `-f` flag will overwrite the existing config
          directory. We can use any config dir that is generated by the `sui genesis`

    --force-regenesis
        A new genesis is created each time this flag is set, and state is not persisted between runs. Only use this flag when you want to start the network from scratch every time you run this command.
        
        To run with persisted state, do not pass this flag and use the `sui genesis` command to generate a genesis that can be used to start the network with.

    --with-faucet[=<FAUCET_HOST_PORT>]
        Start a faucet with default host and port: 0.0.0.0:9123. This flag accepts also a port, a host, or both (e.g., 0.0.0.0:9123). When providing a specific value, please use the = sign between the flag and value: `--with-faucet=6124` or
        `--with-faucet=0.0.0.0`, or `--with-faucet=0.0.0.0:9123`

    --with-indexer[=<DATABASE_URL>]
        Start an indexer with a PostgreSQL database.
        
        Three modes of operation: - Not specified: No indexer is started (unless --with-graphql is set) - `--with-indexer`: Create/use a temporary database in the network's configuration directory - `--with-indexer=<URL>`: Use the provided PostgreSQL
        database URL
        
        When providing a database URL, use the = sign: `--with-indexer=postgres://user:pass@host:5432/db`

    --with-consistent-store[=<CONSISTENT_STORE_HOST_PORT>]
        Start a Consistent Store with default host and port: 0.0.0.0:9124. This flag accepts also a port, a host, or both (e.g., 0.0.0.0:9124).
        
        When providing a specific value, please use the = sign between the flag and value: `--with-consistent-store=9124` or `--with-consistent-store=0.0.0.0`, or `--with-consistent-store=0.0.0.0:9124` The Consistent Store will be automatically enabled
        when `--with-graphql` is set.

    --with-graphql[=<GRAPHQL_HOST_PORT>]
        Start a GraphQL server with default host and port: 0.0.0.0:9125. This flag accepts also a port, a host, or both (e.g., 0.0.0.0:9125).
        
        When providing a specific value, please use the = sign between the flag and value: `--with-graphql=9125` or `--with-graphql=0.0.0.0`, or `--with-graphql=0.0.0.0:9125`
        
        Note that GraphQL requires a running indexer and consistent store, which will be enabled by default even if those flags are not set.

    --fullnode-rpc-port <FULLNODE_RPC_PORT>
        Port to start the Fullnode RPC server on. Default port is 9000
        
        [default: 9000]

    --epoch-duration-ms <EPOCH_DURATION_MS>
        Set the epoch duration. Can only be used when `--force-regenesis` flag is passed or if there's no genesis config and one will be auto-generated. When this flag is not set but `--force-regenesis` is set, the epoch duration will be set to 60
        seconds

    --data-ingestion-dir <DATA_INGESTION_DIR>
        Make the fullnode dump executed checkpoints as files to this directory. This is incompatible with --no-full-node.
        
        If --with-indexer is set, this defaults to a temporary directory.

    --no-full-node
        Start the network without a fullnode

    --committee-size <COMMITTEE_SIZE>
        Set the number of validators in the network. If a genesis was already generated with a specific number of validators, this will not override it; the user should recreate the genesis with the desired number of validators
-h, --help Print help (see more with '--help')
```

Use `sui start --help` to see these options in your console.

### Persist local network state

By default, when using `sui start` the command uses an existing genesis and network configuration if the `~/.sui/sui_config` folder exists and includes a `genesis.blob` file. If the folder doesn't exist, it creates the folder and generates a new genesis configuration. If you pass `--network.config`, the command checks for the network config file and tries to load the genesis blob as per the network config file.

Whenever you stop and start the network without passing the `--force-regenesis` flag, all history is preserved and accessible.

:::info
To generate a custom genesis, use the `sui genesis` command and pass the desired custom values. For more information about possible flags and options, run `sui genesis --help`.
:::

### Access your local full node

Use the following command to retrieve the total transaction count from your local network:

```sh
$ curl --location --request POST 'http://127.0.0.1:9000' \
--header 'Content-Type: application/json' \
--data-raw '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sui_getTotalTransactionBlocks",
  "params": []
}'
```

If successful, the response resembles the following:

```json
{
	"jsonrpc": "2.0",
	"result": 168,
	"id": 1
}
```

## Connect the Sui CLI to your local network

You can use the Sui CLI with any Sui network. By default, it connects to Sui Devnet. To connect to your local network, create a new environment alias named `local` that sets the RPC URL the client uses to your local network.

```sh
$ sui client new-env --alias local --rpc http://127.0.0.1:9000
```

Next, use the following command to set the active environment to the new `local` environment you created.

```
sui client switch --env local
```

The command returns:

`Active environment switched to [local]`

You can check the current active environment with the following command:

```sh
$ sui client active-env
```

The command returns:

`local`

## Show the current active address

The Sui Client CLI uses the active address for command if you don't specify one. Use the following command to show the active address on your local network.

```
sui client active-address
```

The command returns an address, for example:

`0xbc33e6e4818f9f2ef77d020b35c24be738213e64d9e58839ee7b4222029610de`

Use the active address to get test SUI to use on your local network. Use the `sui client addresses` command to see all of the addresses on your local network.

:::info

The address returned when you run the command is unique and does not match the one used in this example.

:::

## Use the local faucet {#use-the-local-faucet}

Transactions on your local network require SUI coins to pay for gas fees just like other networks. You can use the active address with the faucet.

Sui CLI provides the `sui client faucet` command to get coins from the faucet. In the most basic case, run `sui client faucet` and wait up to 60 seconds for the coins to reach your address. Use `sui client gas` to check for the new coins.

:::info

The `faucet` command uses the active address and the active network environment by default. If you need to pass in a different address or faucet server URL, check the `help` menu. If you're using a different network than a local network or the public ones (`fullnode.network.sui.io`), pass the URL to the faucet server.

:::

### Check the gas coin objects for the active address

After you get coins from the faucet, use the following command to view the coin objects for the address:

```sh
$ sui client gas
```

The response resembles the following, but with different IDs:

```sh
╭────────────────────────────────────────────────────────────────────┬────────────╮
│ gasCoinId                                                          │ gasBalance │
├────────────────────────────────────────────────────────────────────┼────────────┤
│ 0x1d790713c1c3441a307782597c088f11230c47e609af2cec97f393123ea4de45 │ 200000000  │
│ 0x20c1d5ad2e8693953fca09fd2fec0fbc52a787e0a0f77725220d36a09a5b312d │ 200000000  │
│ 0x236714566110f5624516faa0da215ad29f8daa611e8b651d1e972168207567b2 │ 200000000  │
│ 0xc81f30256bb04ad84bc4a92017cffd7c1f98286e028fa504d8515ad72ddd1088 │ 200000000  │
│ 0xf61c8b21b305cc8e062b3a37de8c3a37583e17f437a449a2ab42321d019aeeb4 │ 200000000  │
╰────────────────────────────────────────────────────────────────────┴────────────╯
```

## Generate example data

Use the TypeScript SDK to add example data to your network. This requires to start a local network with an indexer and GraphQL: `sui start --force-regenesis --with-faucet --with-indexer --with-graphql`.
Then run the following command from the `sui` root folder:

```sh
$ pnpm --filter @mysten/sui test:e2e
```

For additional information about example data for testing, see [https://github.com/MystenLabs/ts-sdks/tree/main/packages/typescript#testing](https://github.com/MystenLabs/ts-sdks/tree/main/packages/typescript#testing).

## Monitor activity

Use a Sui network explorer to monitor your local network activity. You can build and run one locally or use the **Custom RPC URL** setting available on many online explorers to provide your local network's RPC URL (`http://127.0.0.1:9000` by default).

<ImportContent source="lists/sui-explorers.mdx" mode="snippet" />

## Troubleshooting

If you do not use [Node.js 18](https://nodejs.org/en/announcements/v18-release-announce), you might see the following message:

`Retrying requesting from faucet: Retry failed: fetch is not defined`

To resolve this, switch or update to Node.js 18 and then try again.

## Test with the Sui TypeScript SDK

The published version of the Sui TypeScript SDK might be an earlier version than the version of Sui you installed for your local network. To make sure you're using the latest version of the SDK, use the `experimental`-tagged version (for example, `0.0.0-experimental-20230317184920`) in the [Current Tags](https://www.npmjs.com/package/@mysten/sui?activeTab=versions) section of the Sui NPM registry.
